ADDRESS BOOK Address and 'Phone Number Management for the Psion Series 3A Shareware Program (c) 1994 John W Dawson V1.0, February 1994 1 Introduction Address Book is an Application for the Psion Series 3A which you can use to manage addresses, 'phone numbers, and related information. It has a number of special features which make it more convenient and suitable for this purpose than the standard Database Application built into the Series 3A. These include: o Alphabetic listing and searching of names; o Automatic formatting of addresses for printing envelopes; o Generation of RTF files for printing using a PC/Mac based Word Processor; o Enhanced DTMF dialling: o Variable volume; o Automatic prefixing of charge card account number and PIN o Automatic prefixing of network service codes (for call diversion etc.); o Linking of records, to allow common information to be defined once only but shared by more than entry. The Application manages one or more database of information about an individual or an organisation. Each entry in a database is a record which has fields to hold the following information: Full name; Organisation (e.g. Company for which individual works); Home 'phone number; Work 'phone number; Fax number; Mobile 'phone number; Electronic mail address; Address; Notes. An entry may relate to a person, in which case the Name field will be present and optionally an Organisation. Alternatively the entry may relate to a Company or other organisation, in which case there will no Name, only an Organisation. There are four principle screens: The Find screen lists entries in alphabetical order, and allows alphabetic searches. The Show screen displays a single entry in full. The Update screen allows existing entries to be modified. The Add screen allows new entries to be added. 2 Getting Started To install the Application carry out the following steps: 1 Copy the file ADDRESS.OPA into the \APP directory on the Internal Drive or an SSD. 2 Copy the files ADDRESS2.OPO and DIALOG.OPO into the \OPO directory on the same drive. 3 On the System screen use the "Install" (Psion-I) command to install ADDRESS. The Address Book icon (depicting a book, 'phone, and envelope) should now appear on the screen. 4 You may find it convenient to assign a button to the Application, using the "Assign Button" (Psion-A) command. You can now create an Address Book database by using the "New File" (Psion-N) command (while the highlight is beneath the Address Book icon). In the dialog box specify the name for the database and the drive where it is to be located. It is recommended that databases are stored on the Internal Drive or RAM SSDs, but not Flash SSDs. The Add screen (described fully below) should then be displayed, enabling you to start adding entries to the database. If you have an address database in a standard Series 3/3A format you can incorporate this into the address database using the "Merge Database" (Shift- Psion-M) command (described fully later). If your database was created using the standard Series 3A template (i.e. including the fax label) then set the Database Type to Series 3A. Otherwise if the database was created using the Series 3 template (without fax label) set Database Type to Series 3). Once you have some entries in the database you can go to the Find screen by typing Escape or Diamond. 3 General Points Most of the basic features operate in the 'standard' way. Diamond/Shift- Diamond switches to the next/previous screen. Menu displays the menus. Control-Menu controls the displaying of the Status Window. The Find and Show screens can both be zoomed, by typing Psion-Z or Shift- Psion-Z. Also the Show screen is automatically zoomed to ensure all fields of an entry can be displayed on the screen. The "About Address Book" (Shift-Psion-A) command displays the introductory screen. You can exit cleanly from the Application by using the "Exit" (Psion- X) command in any screen. 4 The Find Screen Entries are listed in alphabetical order. Entries for People are sorted by surname, which is generally taken to be the final space-separated 'word' in a name. E.g. John William Hedges and Peter Hetherington-Whyte would both be listed under H. You can override this, to cater for exceptions such as double-barrelled surnames without hyphens, e.g. Ralph Vaughan Williams which should be listed under V. You should enter such names with a double space between the last forename and the start of the surname (e.g. between Ralph and Vaughan). The ¯ (double chevron eg '>>') character indicates the 'current' entry. Entries for Organisations are sorted by their complete names; e.g. Acme Software Company would be listed under A. You can find an entry by typing the initial letters of its surname (or complete name for an organisation). Use lower case letters only. As you type the program will progressively find the first entry which matches the letters entered, and display the entry with the matched letters highlighted. Upper and lower case characters are treated as equivalent. Accented characters are sorted and matched as the equivalent unaccented character; "‘" is treated as "a", "›" as "o", and "á" as "s". Punctuation characters are ignored when sorting and matching; e.g. O'Regan is listed between Oppenheimer and Oswald, and can be found by typing o r .... If you make a mistake when typing the sequence of initial letters then press the Escape key; this cancels the matching, and enables you to start the sequence again from the first letter. Once the entry you require is displayed on the screen you can select it immediately by typing the digit or shifted letter shown to the left of it. The entry is then shown in full on the Show screen. Enter or Diamond displays the current entry in full. You can move up and down the screen using the Up/Down arrow keys. Page Up/Down move a whole screenfull at a time. Home moves to the first entry, End to the last. Use of any of these keys cancels any matching in progress. 5 The Show Screen This displays the full details for a single entry. Only fields which have information in them are shown. Long lines are wrapped to ensure they appear in full, and the screen is automatically zoomed if necessary to ensure all lines are shown. Up/Down arrow keys move to the previous or next entry (if any). Home moves to the first entry, End to the last. 6 The Update Screen You can update the current entry by using the "Update" (Psion-U) command on the Find or Show screens, or by pressing Diamond on the Show screen. The Update screen is then displayed, showing all the fields for the entry and their current values if any. You can now change these values by typing text on the keyboard. If all or part of a field is highlighted then this is replaced by what you type; otherwise text is added at the cursor position. You can put a line break in the Address field by typing Shift-Enter; the cursor must be on the first line and the second line must be blank. Use the arrow keys to move around within a field or between fields. Use these keys with Shift down to highlight text. Home and End take you to the start and end of the current line. The Delete key removes the highlighted text, or the character to the left of the cursor if nothing is highlighted. You can cut and paste text between fields using Delete or "Copy" (Psion-C) with text highlighted and then "Insert" (Psion-I). If the contents of a field are too long to fit on the screen then they are scrolled automatically as you enter text or move around. The Enter key writes the modified entry back into the database. An entry will not be updated if both the Name and Organisation fields are blank. Use Escape to abandon the update, leaving the entry unchanged in the database. 7 The Add Screen You can add new entries to your database by using the "Add" (Psion-A) command or by pressing the Diamond key on the Update screen or Shift-Diamond on the Find screen. This takes you to the Add screen, whose operation is similar to the Update screen described above, except that all fields are initially blank. 8 Finding Entries The principle way of finding a particular entry is by alphabetical searching by name on the Find screen. However you can also make searches on other fields, using the "Find" (Psion-F) command. In the dialog you then specify the text you are looking for, which field to search (or all fields), whether the search should be case sensitive, and whether the entire field must match the specified text. The program will then tell you how many entries it found which match the specified criteria. If you ask it to display them then the matching entries only are listed on the Find screen. You can then navigate through these entries, display, update, print them etc. as normal. You can revert to displaying the entire database by typing Escape on the Find screen (or Escape twice if a name is highlighted). The program also reverts to displaying the entire database after the Add screen has been entered. 9 Deleting Entries An entry can be deleted using the "Delete" (Psion-D) command, or by typing the Delete key on the Find or Show screens. You are asked to confirm the deletion before the entry is removed from the database. 10 Linking Entries This facility allows more than one entry to share the same common information. The sort of situation where this might be useful is where you have a couple who have the same address and home 'phone numbers, but different work 'phone numbers. Each individual can have their own separate entry, but the common address and home 'phone is only defined in one entry; the other entry refers to this 'parent' entry. If the couple should move then you only need to change the address in one place. Another way of using linking is to set up a 'parent' entry for a Company, and have several linked entries for individuals in the Company. You can create a new entry linked to an existing 'parent' entry using the "Add Linked Entry" (Psion-L) command. The 'parent' entry must be the current entry on the Find or Show screen. The Add screen will then be displayed, with the field contents derived from the 'parent' shown in grey. These values cannot be modified, but can be replaced by typing new contents. You can link an existing entry to an existing 'parent' using the "Link" (Shift-Psion-L) command. First select the entry to be linked on the Find or Show screen and type Shift-Psion-L. Then select the required parent and type Shift-Psion-L again. An entry can only be linked to a single 'parent', but a 'parent' entry can have any number of other entries linked to it. When a linked entry is displayed on the Show screen then for any of its fields which are blank the contents of the field in the 'parent' entry are shown instead. You can suppress the showing of field contents derived from the 'parent' by entering a single space in the field. When you update a linked entry fields derived from the 'parent' are shown in grey and cannot be changed, only replaced. You can remove a link from an entry with the "Remove Link" (Shift-Psion-U) command. You are asked to confirm the removal. 11 Importing Data If you have existing Data files containing address information then you can import this into an Address Book database. If the Data files conform to the standard template supplied with the Series 3 or Series 3A then you can use the "Merge Database" (Shift-Psion-M) command to do this directly. As well as specifying the name and drive for the file to be imported you must specify these characteristics of the imported file: o The Database Type - whether it conforms to the Series 3 layout, or to the Series 3A layout which has an extra Fax label; o The Name Structure - determines how the Name field is interpreted: as a person's name with the Surname First or Last, or as the name of an Organisation. Note, if the merged data file actually contains a mixture of entries for people and organisations, you can merge it using the surname first or last options, then use the "Make Organisation" (Psion-O) command to convert the entries which are actually for organisations. This command moves the Name field to the Organisation field. If you have data in a file that does not conform to one of the standard templates then it is very easy to write a simple OPL program to convert your file to the format of an Address Book database file. The structure of an Address Book record is as follows: Index% Link% Surname$ Forenm$ Organ$ Home$ Work$ Fax$ Mobile$ Email$ Addr1$ Addr2$ Notes$ Index% and Link% are numeric fields used internally by the program. Index% should be set to a value unique for each entry and greater than 1, taking the value of POS + 1 for each record would be suitable. Link% should be set to 0 for each entry, unless you want to create linked entries, in which case it should be set to the value of Index% for the 'parent' entry. The other fields are all strings whose meanings should be obvious from their names. Once you have created a file with the above record structure you can open it directly with the Address Book Application. Alternatively you can merge it into an existing Address Book file (see below). You can also merge the contents of another Address Book file into the current database, using the "Merge Addresses" (Psion-M) command. Note that in this case the program makes two passes through the input file, in order to correctly maintain link information. Note that although Address Book file are OPL Databases, they cannot be created or viewed using the built-in Database Application, since they contain non- string fields. 12 DTMF Dialling You can dial the current entry on the Find or Show screen by typing Dial (Psion-Help). This displays the Dialling screen which lists all the telephone numbers for that entry. Select the number you wish to dial using the Up and Down keys. The Tab key dials the number exactly as shown. Enter prefixes the "dial out" code, e.g. to make an outside call via a switchboard. Type c to automatically prefix the account number and PIN for a BT charge card call (or similar). Type d to dial the number with the code and terminator for a special service (such as BT Star Services Call Diversion). Type Escape to quit from the Dial screen. After any of these buttons are pressed there is a short delay; this allows you to position the loudspeaker correctly for successful dialling. You can dial further digits by pressing any of the 0 to 9 and *, # keys while the Dial screen is displayed. If a 'phone number entry contains non-diallable characters, then only the digits preceding the first such character will be dialled. E.g. if an entry contains: "0123 456789 x321" then only 0123 456789 will actually be dialled. This version of the program does not support international dialling. However numbers should be dialled correctly when making calls within the same country, even where the numbers have been entered in standard Psion international format, so long as any national prefix is included (e.g. 1 321 4567890 [USA]). Note the c and d buttons will not be displayed or activated until you have set up an account number and PIN or service code; use the "Dialling Setup" (Shift-Psion-D) command to display the Dialling Setup Dialog. When setting up the Divert Code specify both the code prefix and the terminator, separated by a space. E.g. for Star Services "Divert on No Reply" you should set *61* #. You can also set the code required to obtain an outside line. E.g. if you have to dial 9 and then wait for a second dial tone you should set 9,. The other fields allow you to specify the duration of the tones, the pause between tones, and the length of a delay; units are 1/32s of a second. You can also set the volume of the tones; allowed values are 0 to 5, with 5 the quietest. (5 seems to give the most reliable results with most 'phones.) 13 Printing The program is designed to print by outputting directly to a host computer (IBM PC or Apple Macintosh) via the Serial Link. It can produce files either in Rich Text Format (RTF) or in plain text format. RTF files can be printed using a compatible word processing program, such as Microsoft Word. They contain all necessary formatting information, and should not require further formatting. Text files can either be sent directly to a printer, or imported into any word processing program for formatting and printing. To start printing use the "Print" (Psion-P) command (after first establishing the serial connection). In the dialog you can then specify the Destination disk and directory path where the print file will be created, as well as the Format (RTF or Text). The file will be given the same name as your database file, but with extension .RTF or .TXT. You can choose from two Layouts: o Listing - for listing the full details of entries. This prints all fields in an entry, with the corresponding labels. o Envelopes - for printing addresses directly onto envelopes. This prints the Name and/or Organisation, followed by the contents of the two Address lines. Each element in the Address which is separated by a comma is printed on a separate line, except that house numbers are printed on the same line as the following street name, even if separated by a comma. Print Organisation is only relevant when printing envelopes, and controls whether the Organisation is printed in addition to the Name. If you select Prompt then for each entry which has both a Name and Organisation you will be asked if you want the Organisation printed. For entries which have no Name the Organisation is always printed. Entries controls which entries are printed. You can choose to print All entries in the database, or selected Individual entries. Additionally if you have used the "Find" command to select a subset of entries, then you can also choose to print these Selected entries. If you specified All or Selected entries, then these are printed immediately you terminate the dialog with Return. Once this is complete (the "Printing" message is no longer flashing) you can break the serial connection, and print the file on the host. If you specified Individual entries then you must select each entry you want printed, by using the "Print Entry" (Psion-P) command. When all required entries have been printed you terminate printing with the "Finish Printing" (Shift-Psion-P) command; only then can you break the serial connection and print on the host. Note for Macintosh users: you should set the Host to Mac in the Print Dialog. This gets round some of the problems associated with transferring RTF files to the Mac, in particular the handling of characters with codes greater than 127 (e.g. accented characters), which are different in the PC and Mac character sets. In theory this should be catered for by the RTF format, where such characters are represented by hexadecimal number strings. The RTF file also includes an indication of the "origin" of the file (e.g. PC or Mac). Hence the translator reading the file should be able to convert these characters to the equivalent characters in the destination machine's character set. In practice I have found the word processor I use (Microsoft Word V4.0 for Macintosh) does not handle this completely; it converts the first few characters correctly, but then gives up! This may be a reflection of the fact that there is no "standard" PC character set. The solution I have adopted is to output such characters as the actual characters themselves, and then rely on the conversion built into the MCLINK program to convert them to the Mac character set. This requires that "*.RTF" is added to the list of file extensions in the MCLINK.EXT file. If Host is set to Mac then the RTF file is generated with "Origin" set to "Mac", i.e. the RTF translator on the Mac is fooled into thinking the file was generated on a Mac and will not attempt any conversion of characters. You can change the layout and appearance for printing both Lists and Envelopes individually, using the "Print Setup" (Psion-Y) command, which displays the Print Setup Dialog. If you want to change values in any line of this dialog you must use the Tab key. Use the Up and Down keys to move between lines. On the Page line you can specify the Width and Height of the paper (in inches), and also the Orientation (portrait or landscape). Note the Word Processor I use (Microsoft Word for Macintosh V4.0) does not appear to take notice of paper orientation commands in RTF files. Therefore it may be necessary to set this manually from within your Word Processor before printing. On the Margins line you can specify the sizes of the Top, Left, Bottom, and Right margins (in inches). For List output you can also specify the Tab position, where field values will be printed to the right of their corresponding labels. On the Font line you can specify the Name, Family, and Size (in points) for the font. You can use any combination that your Word Processing program will recognise. For Envelopes you can also specify printing in Bold and/or Italic. The Enter key ends the dialog and applies the changes. Use Escape to abandon the changes. 14 Problems and Troubleshooting At time of writing this I am not aware of any outstanding bugs in the program. However it has not been rigorously tested to the same standards as commercial software. Also it is a very complex program which does rather a lot of dynamic memory allocation and PEEKing and POKEing. Hence there is considerable scope for cocking things up! I cannot therefore be held responsible for any consequences of using this program. The most likely problems to be encountered are associated with running out of memory. This is most likely when attempting to display a new screen or dialog. The program is designed to trap such occurrences and either abandon what it was trying to do or exit gracefully. If the program should exit in an uncontrolled way, or has to killed off (because it appears to be locked up), then when it restarts it will have to rebuild its internal index tables. This can take a few minutes, but it does indicate its progress. If the program should start behaving erratically (e.g. listing entries in wrong order or missing out some entries) this may indicate corruption of its internal index tables. It may be possible to deal with this by exiting normally and deleting the index file it creates (this has same name as the main database file, but with .IDX extension. Then when the program restarts it will rebuild its tables, hopefully correctly! If you have queries or comments about this program I can be contacted at 19, St Edward's Rd. Reading Berkshire England Telephone: +44 734 666185 Please call outside working hours if possible! 15 Registration I am making this program available as Shareware. There is no registration procedure; the software as distributed is fully operational. However if you find this program useful then I would ask you to send a donation (suggested 10.00 UK pounds Sterling) to a charity I am closely involved with. Reading Steiner School Project (Registered Charity No. 297857) is developing education in the Reading area based on the work of the Austrian educationalist and philosopher Rudolf Steiner. Please make cheques etc. payable to R.S.S.P., and send them to Department ADBK Alder Bridge School Mill Lane Padworth Reading RG7 4JU Please do not send any technical queries etc. to the School! Please do distribute this program freely, providing you do not make any charge (other than to cover reasonable costs of distribution) and you include these notes. 16 Future Developments I have developed this program for my own use, so its facilities and operation very much reflect my own requirements. However there are a number of obvious ways it could be extended and developed, to make it more useful to a wider range of people. These include: o Making the record structure and labels user configurable; o Dialling of international calls, perhaps through interface to World; o Direct output to printer, using resident drivers; o A 'cut down' version for the Series 3. I would be very happy to hear from anyone who would like to collaborate on any of these, or who has any other good ideas for developments.